Summary

This PR adds a TypeScript sibling package for GCache under packages/gcache-ts, published as @rungalileo/gcache, plus TypeScript CI and Codecov upload. It consolidates the previously stacked milestone PRs into one reviewable PR.

Supersedes: #133, #134, #135, #136.

What changed

Package + CI

• Adds a pnpm workspace and TypeScript package build/test/typecheck scripts.
• Adds ESM/CJS builds, generated type declarations, and package exports.
• Adds .github/workflows/typescript.yaml for install/typecheck/test/build.
• Uploads TypeScript coverage to Codecov from packages/gcache-ts/coverage/lcov.info with the gcache-ts flag.

Local-only GCache MVP

• Adds explicit gcache.enable(fn) / gcache.disable(fn) APIs backed by Node AsyncLocalStorage.
• Keeps caching disabled by default, with nested and parallel async scopes isolated.
• Adds explicit key builders via GCacheKey / GCacheKeyConfig.
• Adds local TTL caching, max-size eviction, delete, flushAll, and fail-open behavior.

Redis TTL layer

• Adds optional Redis-backed distributed TTL caching.
• Implements local → Redis → fallback read-through behavior.
• Supports eager Redis client injection or lazy createClient.
• Adds a versioned timestamped Redis JSON envelope with default/custom serializer support.
• Adds cross-layer delete/flushAll and fail-open Redis read/write/delete/flush behavior.

Runtime config + rollout controls

• Adds runtime cacheConfigProvider support with fallback to per-function defaultConfig.
• Adds per-layer TTL/ramp controls.
• Adds injectable ramp sampling so rollout behavior is deterministic in tests.
• Treats missing/invalid config as layer-disabled and falls through instead of breaking app requests.
• Preserves fail-open behavior for config provider errors.

Observability + operational safety

• Adds metrics hooks for requests, misses, disabled paths, errors, invalidation calls, get/fallback/serialization timers, and serialized value size histograms.
• Adds Prometheus support via prom-client, with custom registry/prefix and duplicate collector reuse.
• Adds custom metrics adapter support for non-Prometheus integrations.
• Separates cache plumbing errors from fallback/business-logic errors in labels.

Targeted invalidation + watermarks

• Adds trackForInvalidation on cached functions.
• Adds gcache.invalidate(keyType, id, { futureBufferMs }).
• Adds Redis Cluster-compatible watermark keys like {urnPrefix:keyType:id}#watermark.
• Adds configurable watermark TTL and documents that it should exceed max cache TTL.
• Suppresses Redis/local writes while an invalidation watermark is active to avoid stale write races.
• Documents local-cache consistency limitations and recommends disabling local cache for strongly invalidated mutable data.
• Fails open with warning/error metrics around watermark read/write failures.

Testing

Tests are written in behavioral Given/When/Then style.

Validation run on the peak branch:

• pnpm install --frozen-lockfile
• pnpm ts:gcache:typecheck
• pnpm ts:gcache:test — 47 tests, coverage: 97.05% statements / 92.62% branches / 98% functions / 97.27% lines
• pnpm ts:gcache:build

Intentionally left for later

• Framework integrations / middleware helpers
• cachedObject convenience API
• Expanded examples
• Release hardening / publishing workflow